---
title: Viewport Plugin
description: Provides the essential <Viewport /> component, the scrollable container for all PDF content in Svelte.
searchable: true
---

# Viewport Plugin

The Viewport Plugin is a foundational element for any viewer. It provides the `<Viewport />` component, which acts as the scrollable "window" through which users see the PDF pages. It is responsible for tracking its own dimensions and scroll position and communicating that information to other plugins.

## Installation

The plugin is available as a separate NPM package.

```sh npm2yarn
npm install @embedpdf/plugin-viewport
```

## Registration

Import `ViewportPluginPackage` and add it to the `plugins` array. It is highly recommended to include this plugin in any viewer build.

```typescript {3, 12-14}
import { createPluginRegistration } from '@embedpdf/core'
// ... other imports
import { ViewportPluginPackage } from '@embedpdf/plugin-viewport/svelte'

const plugins = [
  // ... other essential plugins
  createPluginRegistration(LoaderPluginPackage, { /* ... */ }),
  createPluginRegistration(ScrollPluginPackage),
  createPluginRegistration(RenderPluginPackage),

  // Register and configure the viewport plugin
  createPluginRegistration(ViewportPluginPackage, {
    viewportGap: 10, // Adds 10px of padding inside the viewport
  }),
]
```

## Usage

The plugin provides the `<Viewport />` component, which you use to wrap your `<Scroller />`, and composables to interact with it programmatically.

### The `<Viewport />` Component

The `<Viewport />` component is the main scrollable container for your PDF. You should place it in your layout and ensure it has a defined size (e.g., `height: '500px'` or a flex class). It automatically handles listening for scroll and resize events.

```svelte
<script lang="ts">
import { Viewport } from '@embedpdf/plugin-viewport/svelte';
import { Scroller } from '@embedpdf/plugin-scroll/svelte';
</script>

<div style="height: 500px; display: flex;">
  <Viewport class="flex-grow bg-gray-100">
    <Scroller {RenderPageSnippet} />
  </Viewport>
</div>
```

### Programmatic Scrolling

You can control the viewport's scroll position from any other component using the `useViewportCapability` composable. This is useful for features like a "scroll to top" button or navigating from a table of contents.

```svelte
<script lang="ts">
import { useViewportCapability } from '@embedpdf/plugin-viewport/svelte';

const viewportCapability = useViewportCapability();

const scrollToTop = () => {
  viewportCapability.provides?.scrollTo({ x: 0, y: 0, behavior: 'smooth' });
};
</script>

<button onclick={scrollToTop}>Scroll to Top</button>
```

### Monitoring Scroll Activity

The plugin also provides a `useViewportScrollActivity` composable that returns the current scrolling state. This is useful for creating UIs that react to user scrolling, such as auto-hiding toolbars.

```svelte
<script lang="ts">
import { useViewportScrollActivity } from '@embedpdf/plugin-viewport/svelte';

const scrollActivity = useViewportScrollActivity();
</script>

<div>
  {scrollActivity.isScrolling ? 'Scrolling...' : 'Idle'}
</div>
```

## Live Example

This example demonstrates a viewer with a toolbar that can programmatically scroll the viewport. It also includes an indicator that shows when the viewport is actively scrolling.

import { ViewportExample } from '../code-examples/viewport-example';

<ViewportExample />

## API Reference

### Configuration (`ViewportPluginConfig`)

| Option | Type | Description |
| :--- | :--- | :--- |
| **`viewportGap`** | `number` | The padding (in pixels) to apply around the content inside the viewport. <br />**Default**: `10` |
| **`scrollEndDelay`** | `number` | The time in milliseconds after the last scroll event before the `isScrolling` state is set to `false`. <br />**Default**: `300` |

### Component: `<Viewport />`

A `div`-based component that acts as the scrollable container. It accepts all standard `div` attributes like `style` and `class`.

### Composable: `useViewportCapability()`

Connects your component to the viewport's functions.

#### Returns

| Property | Type | Description |
| :--- | :--- | :--- |
| **`provides`** | `ViewportCapability \| null` | An object with methods to interact with the viewport, or `null` if the plugin is not ready. |

#### `ViewportCapability` Methods

| Method | Description |
| :--- | :--- |
| **`getMetrics()`** | Returns a `ViewportMetrics` object containing the current dimensions, scroll offsets, and total scrollable area. |
| **`scrollTo(position)`** | Programmatically scrolls the viewport. The `position` object can include `x`, `y`, `behavior: 'smooth'`, and `center: true`. |
| **`getBoundingRect()`**| Returns the `Rect` of the viewport element relative to the browser's viewport. |

### Composable: `useViewportScrollActivity()`

A composable for tracking the scroll state of the viewport.

#### Returns

A reactive object with the following properties:

| Property | Type | Description |
| :--- | :--- | :--- |
| **`isScrolling`** | `boolean` | `true` if the user is currently scrolling or a smooth scroll animation is in progress. |
| **`isSmoothScrolling`**| `boolean`| `true` only when a smooth scroll animation initiated by `scrollTo` is in progress. |

